Appendix A 
Mem Calls 




INITIALIZATION AND TERMINATION ROUTINES 


MenuBootlnit (not completed) 

input None, 
output None. 

Called when SetTSPtr is called. 


MenuS tartup 

input useriDtWORD»user ID that the Menu Manager can use, mainly to allocate memory. 
zeropgrWORD - zero page Menu Manager can use, must be on page boundary. 

output None. 

Initializes system menu bar with no menus, and makes it the current menu bar. 

Calls Desktop in the Window Manager to reserve space for the bar. 

Menu Manager opens a grafPott 

Calls DrawMenuBar to draw an empty system menu bar. 


MenuShutDown 

input None, 
output None. 

Closes die Menu Manager's port and frees any allocated menus. 


MenuVersion 


input None. 






NewMenuBar 


inputs: theWindowrLONG - pointer to window's port, owner of menu bar, zero for system, 
output: BarHandle:LONG - handle of menu bar. 

NewMenuBar will create a default menu bar with no menus. MenuS tartup calls 
NewMenuBar to create a default system menu bar. If you are only going to use one 
system menu bar, NewMenuBar will not have to be called. The default size of the menu 
bar is, upper left comer matches die port, and the width is the width is the width of the 
screen. The height of the bar is 13. The menu bar is visible and has default colors of black 
text on a white background. 


NewMenu 

input: MenuString:LONG - pointer to a menu/item line list 
output: MenuHandle:LONG - handle of menu, zero if error. 

NewMenu allocates space for a menu and its items. You pass a pointer to a menu/item line 
list which is a text string that describes the menu tide and its items. See MENU LINES AND 
ITEM LINES for the format needed. The MenuHandle returned can then be inserted in a 
menu bar via an InsertMenu calL 

Call DisposeMenu to deallocate the menu when finished. 
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DisposeMenu 

input: MenuHandle:LONG - previously allocated via NewMenu. 
output: None. 

Frees die memory used by MenuHandle. The menu will no longer be usable. 


Warning; The menu is not taken out of the menu list, call DeleteMenu to do 
that To delete a menu from the menu list and free it's memory you 
could do something like this: 


pha 

pha 

pea MenuID 
GetMHandle 


Space for returned handle. 

ID of menu to delete. 

Get the handle of the menu. 
Leave menu handle on stack. 


pea MenuID ID of menu to delete from list. 

DeleteMenu Delete menu from list. 


DisposeMenu 


Handle still on stack. 
Deallocate menu record. 


FixMenuBar 

input None. 

output MenuHeightWORD - height of the menu bar. 

This routine will compute standard sizes for your menu bar and menus; 

FixMenuBar will search all the menu title fonts and use the tallest one to compute the 
. height of the menu bar, add it to Bar.top, and store it in Bar.bottom. It will set the 
TitleWidth width for every menu TitleWidth that is given as zero. Finally it will call 
CalcMenuSize for each menu in the menu bar. 
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CalcMenuSize 


inpud new Width; W ORD - n um ber of pixels wide the menu should be, or zero. 
newHeighdWORD - number of pixels high the menu should be, or zero. 
MenuNumWORD - menu ID number. 

output; None. 

This call lets you set menu dimensions, or have the Menu Manager do it The Menu 
Manager will calculate die width for you if newWidth is zero and die height if newHeight is 
zero. 

To compute the width the Menu Manager will find the widthest item in the menu plus room 
for a mark and command key. A default width will be used if the menu does not contain any 
item text 

To compute the height, the Menu Manager will add up the font height of each item plus four, 
or use the value found in the font index of ItemFlag if bit 14 of ItcmFlag is set 

This routine is called for each menu by the Menu Manager when FixMenuBar is called. 
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USER INTERACTION ROUTINES 


MenuSelect 

input: TaskRee:LONG - points' to Task record which contains point of button down. 
BarHandle:LONG - handle of menu bar, zero for system menu bar. 

output: None (TaskData' field of Task record contains return IDs). 

Called when the a button goes down on a menu bar (see FindWindow if using the Window 
Manager). The routine win take care of drawing highlighted titles, pulling down menus, and 
user interaction. Ibis is handled automatically for the system menu bar when using 
TaskMaster in Window Manager. 

If a selection is made the low order WORD of the TaskData' element in the Task record will 
contain the ID number of the item selected, and the high order WORD will contain the 
menu's ID number. If there is a selection, the menu's tide wiU be left hightighted. See 
HiliteMenu to redraw the tide as normal 

If no selection is made by the user the low order WORD of the TaskData' element in the 
Task record wfll be zero. 

BarHandle becomes the current menu bar. 

The structure of TaskRec is: 


what 

WORD 

message 

LONG 

when 

LONG 

where 

LONG 

modifiers 

WORD 

TaskData 

LONG 


Event record portion, unchanged from GetNextEvent. 


Extended portion for TaskMaster. 
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MenuKey 

input: TaskRec:LONG - pointer to Task record which contains the character to check. 
BarHandle:LONG - handle of menu bar, zoo for system menu bar. 

output: None (TaskData 1 field of Task record contains return IDs). 


Maps the given character to the associated menu aid item for that character. When you get a 
key-down event with the Command key held down-or auto-key event, if the command 
being invoked is repeatable-call MenuKey with a pointer to a Task record that contains the 
character and the state of the modifier keys (die format is the same as an Event record, see 
Event Manager). The match will only occur if it is indicated in the Task record that the 
co mman d key was down. MenuKey highlights the a p p r o priate menu ride if the key 
matches, and returns Selection. 

The items are searched starring with the first menu in the menu list and all the items in the 
menu starting with the first Then the second menu, and so on. The given key is compare 
with every item's primary keyboard equivalent of every item. If no match is found, the cycle 
is repeated, this time comparing to each item's alternate keyboard equivalent 

There generally there should never be more than one item in the menu list with the same 
keyboard equivalent, but if there is, MenuKey returns the first one it encounters. 

MenuKey will not convert lower case characters to upper case. If you want to match on 
either upper car lower case, set the primary character to the upper case character and the 
alternate to the lower case character. 

If a selection is made the low order WORD of the TaskData' element in the Task record will 
contain the ID number of the item selected, and the high order WORD will contain the 
menu's ID number. If there is a selection, the menu's tide will be left highlighted. See 
HiliteMenu to redraw the tide as normal. 

If no selection is made by the user the low order WORD of the TaskData' element in the 
Task record will be zero. 

BarHandle becomes the current menu bar. 

See MenuSelect for a description of TaskRec. 
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MenuRefresh 


input: RedrawRoutineiONG - address of routine in your applicadon. 
output: None. 

Note: This is called only when using the Menu Manager without the 
Window Manager. 

RedrawRoutine is called when the Menu Manager can not restore die screen under a menu. 
First the Menu Manager will tty to allocate a buffer large enough to save the screen part 
before it draws the menu. If the buffer is allocated the screen will be restored from it and 
then deallocate the memory buffer. If the buffer can not be allocated die Menu Manager will 
try to call the Window Manager (via the call the Window Manager made to MenuRefresh 
during initialization) to refresh the screen when the menu goes away. If no buffer can be 
allocated and the Window Manager isn't installed, the Menu Manager will call 
RedrawRoutine to refresh the screen under the menu. 

The RedrawRoutine should look something like this: 

Refresh START 

♦ 

rect_addr equ 6 Offset down stack to RECT pointer. 


Needed operations to redraw the 

screen inside the given RECT. 


Remove the given pointer from the stack: 



Ida 

0,s 


address down 





sta 

4,s 

the stack. 


Ida 

2»s 



sta 

6,s 



pla 


Move the stack back 

the return 





pla 


address. 


rd 


Return to the Menu 

Manager. 
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DRAWING 


DrawMenuBar 

input: None, 
output None. 

Draws the current menu bar, along with any menu titles on the bar. 

HQiteMenu 

input Hilite:WORD»FALSE to draw normal, TRUE to highlight the tide. 

MenuNum:WORD •• menu's ID. 

output None. 

MenuNum is the the menu's ID. Its tide is drawn using the menu bar's normal color if Hilite 
is FALSE, or hilite color if TRUE. HiliteMenu should be called with Hilite FALSE, and 
the menu ID of the selected menu, after the application has finished acting on a menu 
selection. 

FlashMenuBar 

input None, 
output None. 

This will redraw the entire current menu bar using the bar's hilite color and then again using 
its normal color. 
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MENU AND ITEM SHUFFLING 


InsertMenu 

input: AddMemuLONG - handle of menu to insert 

InsertAfter: WORD - menu ID, zero to insert at front 

output: None. 

Inserts AddMenu into the current menu bar after InsertAfter, or at the front of the list if 
InsertAfter is zero. DrawMenuBar should be called to redraw the new menu bar after 
InsertMenu. 


DeleteMenu 

input: MenuNum:WORD - menu ID of menu to delete, 
output: None. 

MenuNum is take out of current menu bar. DrawMenuBar should be called to redraw the 
new menu bar after DeleteMenu. The menu is not deallocated, call DisposeMenu to do 
that. 


Insertltem 

input: AddltemLONG - address of item line to insert. 

InsertAftenWORD - item ED, zero to add to front, $FFFF to append to end of menu. 
MenuNum:WORD ■ menu ED number to add item to, zero for first menu. 

output None. 

, Inserts an item into die ItemList after InsertAfter. If InsertAfter is zero, the item will be 
inserted at the front of MenuNum. If InsertAfter is SFFFF, the item will be appended at the 
end of MenuNum If MenuNum is zero, the menu will be considered the first menu. Call 
CalcMenuSize to resize the menu if needed afterward. See MENU LINES AND ITEM 
LINES for the definition of an item line. 
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Deleteltem 


input: ItemNumiWORD - item ID of item to delete, 
output: None. 

ItemNum is taken out of Ite mLis t of its menu in the current menu bar. Call CalcMenuSize 
to resize the menu if needed afterward. 
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MENU BAR ACCESS 


SetSysBar 

input BarHandle:LONG - handle of new system menu bar, 
output None. 

Handle of new system menu ter is given. The system menu bar becomes the current menu 
bar. 


GetSysBar 

input None. 

output BarHandle:LONG - handle of the system menu ter. 

Returns the handle of the system menu ter. 

SetMenuBar 

input BarHandle:LONG - handle of current menu bar. 
output None. 

Handle of menu bar to make current is given. If you want the system menu bar to be the 
current menu ter, pass zero for BarHandle. 

GetMenuBar 

input None. 

output BarHandlerLONG - handle of current menu bar. 

Returns the handle of the current menu bar. 
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CountMIteins 

input: M©nuNum:WORD - menu's ID. 

output NumOfltems:WORD - number of items in menu. 

Returns the number of items, including any dividing lines, in the menu. 


SetBarColors 

input NewBarColonWORD - normal bar color. 

NewInvertCote: WORD-selected bar cote. 
NewOutColonWORD - Outline cote in bits 7-4. 


output None. 

Normal Colon bits 0-3 = text cote when not selected. 

bits 4-7 = background cote when not selected, 
bits 8-15 s zero. 

Negative to not change normal cote. 


HUite Color. bits 0-3 a text cote when selected. 

bits 4-7 » background cote when selected, 
bits 8-15 ® zero. 



bits 4-7 = cote of menu bar outline, menu outline, underlines, and 


dividing lines 
bits 8-15 = zero. 


Negative to not change outline cote. 


Cote of current menu bar is set to given values that are not negative. Call DrawMenuBar 
to draw menu bar in new colors. 
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GetBarColors 


input: None. 

output: Colors:LONG - colors of menu bar. 

Returned menu bar colors are returned in one LONG of which: 


bits 31-24 
bits 23-18 
bits 19-16 
bits 15-12 
bits 11-8 
bits 7-4 
bits 3-0 


= zero. 

= color of menu bar outline, menu outline, underlines, and dividing lines 
® zero. 

s background color when selected. 

® text edict when selected, 

* background color when not selected. 

® text color when not selected. 


SefTitleStart 

input: XS tart:WORD - menu bar title starting position, 
output: None. 

XStart is the number of pixels horn the left side of the menu bar that the titles should start. 
Xstart should be at least 1. Zero will over write the left side outline of the menu bar. 127 is 
the maximum value allowed. 


GetTitleStart 

input: None. 

output: XStart:WORD - menu bar title starting position. 

XStart is die number of pixels from the left side of the menu bar that the tides start from. 
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MENU RECORD ACCESS ROUTINES 


GetMHandle 

input: MenuNum: WORD - menu ID. 

output: MenuHandle:LONG - handle of menu, zero if mor. 

Handle of menu with an ID number that matches menuNum is returned, or zero if the menu 
is not found. 

SetTitleWidth 

input: NewWidthtWORD - new width of tide. 

MenuNum:WORD - menu ID. 

output: None. 

Sets the width of a tide. This is the area where the user can select a menu and the area that is 
inverted when the tide is highlighted. 

GetTitleWidth 

input: MenuNum:WORD - menu ID. 

output: TheWidth:WORD - width of tide, zero if error. 

Returns the width of a tide. This is the area where the user can select a menu and the area 
that is inverted when the tide is highlighted. 
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SetMenuFlag 

input: NewValue:WORD - new bit value to set or dear. 
MenuNunrWORD - menu ID. 


output: None. 


Possible New Values: 


EnableMenu 

DisableMenu 

UnfaHiteMenu 

HiliteMenu 

ColorReplace 

XORhilite 

StandardMenu 

CustomMenu 


$FF7F Menu will not be dimmed and will be selectable. 

$0080 Menu will be dimmed and not selectable. 

$FFBF Menu will appear in its highlighted state. 

$0040 Menu will appear in its normal (unhighlighted) state. 
$FFDF The menu's title and background will be redrawn to hilite. 
$ 0020 The menu's title area will be XORed to hilite. 

$FFE7 The menu will be considered a standard menu. 

$0010 The menu will be considered a custom menu. 


If you change a flag that affects the appearance of a menu tide you should also call 
DrawMenuBar after SetMenuFlag to redraw the tides in their new state. 


GetMenuFIag 

input: MenuNum:WORD - menu ID. 

output: MenuState:WORD - desired bits from MenuFlag. 

Returns MenuNumJVfenuFlag (see MENU RECORDS for definition). 

SetMenuTitle 

input: NewStrg:LONG - Address of string to replace ItemName. 
MenuNum: WORD»menu ID. 

output: None. 

The value in NewStrg is moved into the menu’s TideName. 


f PiliT View" 

flppendiH fi 


16 


August 13, 1986 



GetMenuTitle 


input: MenuNum:WORD - menu ID. 
output: TheTitle:LONG - pointer to TitleName. 
Returns a pointer to the tide of a menu. 

SetMenuID 

input NewEDfW'ORB»new ID to be assigned 
MenuNum:WORD - current menu EX 

output: None. 

The menu is assigned the given ID number. 
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ITEM RECORD ACCESS ROUTINES 
Setltem 

input NewStrg:LONG - Address of suing to replace ItemName. 
ItemNum:WORD - item ID. 

output None. 

The item’s ItemName pointer is replaced with MewStrg. 

Getltem 

input ItemNumtWORD - item ID. 
output ItemStrgiONG-pointertoItemName. 

Returns a pointer to an item's text string. 


Enableltem 






Disableltem 


input: ItemNum:WORD - item ID. 
output: None. 

Item win appear dimm ed, and will not be selectable. 

Cbeckltem 

input: CheckedtWORD - TRUE to check item, FALSE to uncheck item. 
ItemNunrWORD - item ID. 

output: None. 

Item will appear with a check mark to the left of the item's text, or nothing wiU appear if 
Checked is zero. 

SetltemMark 

input: Mark:WORD - character to mark item with, zero for no mark. 

ItemNum:WORD - item ID. 

output: None. 

Item wiE appear with the character given to the left of the item's text, or the mark will not 
appear if Mark is zero. 

GetltemMark 

, input: ItemNunrWORD - item ID. 

output: MaricWORD ~ character that marks item, zero » no mark. 
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SetltemStyle 


input: ChStylerWORD - text style to use on item's text 
ItemNunrWORD - item ID. 

output: None. 

Bits in ChStyle are set to enable special text drawing. Bits affected are: 

$0001 - Bold 

$0002 -Italic. 

$0004 - Underscore: . 

Bits 0-2 of chStyle are all used to set the item's text style. For example: 

chSfyle « $0007 The item is printed as bold italic and underscored. 

chStyle » $0005 The item is printed as bold and underscored 

chStyle - $0000 The item is printed as plain (no bold italic or underscore). 


GetltemStyle 

input ItemNum:WORD - item ID. 

output: ChStyle:WORD - text style to use cm item's text 

Bits in ChStyle are set to enable special text drawing. Bits affected are: 

$0001 - Bold 

$0002 - Italic. 

$0004 - Underscore . 


SetltemFlag 


I m Mil i n 


ItemNum: WOR.D - item ID. 
output: None. 

This call is used to set desire states of an item. Input flags are: 


Emsnea MsslYMus 

Underline item. $0040 

Not underline an item. $FFBF 

Use XOR highlighting, $0020 




Use redraw highlighting. 


$FFDF 





GetltemFlag 

input: ItemNumrWORD - item ID. 

output: Divide:WORD - current underline value. 

XOR:WORD»cunent highlighting method 

Outputs are: 

GldDivide 0 = no underline 1 * underline 

OldXOR 0 = redraw to highlight 1 = XOR to highlight 

SetltemlD 

input: NewED:WORD - new ID to be assigned. 

ItemNunxWORD - current item ID. 

output: None. 

The item is assigned the given ID number. 


SetltemBIink 

input: CountWORD - number of times item should blink when selected 
output: None. 

This call affects all menu bars, system and window. When an enabled item is selected by the 
user the item blinks briefly to conform the chioce. Normally, your application shouldn't be 
concerned with this blinking; the user sets it with the Control Panel desk accessory. If 
you’re writing a desk accessory like the Control Panel, though, SetltemBIink allows you • 
to control the duration of the blinking. The Count parameter is the number of times menu 
items will blink. 
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MISCELLANEOUS ROUTINES 


GetMenuMgrPort 
input: None. 

output MenuMgrX,ONG - pointer to Menu Manager's port. 

(jetting the Menu Manager’s port might be useful if you would like to change is font 

MNewRes 

input: None, 
output None. 

Called when the screen resolution changes. Menu Manager makes needed adjustments for 
the new resolution and redraws the current system menu bar. 


InitPalette 

input None, 
output None. 

Call when you've changed the color palattes. This will reinitize the palettes needed 
for the color Apple logo in the system menu bar. 
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Constants 


Masks for MemiRag: 


M_INVIS 

$04 

FASLE if menu is visible (not completed). 

M_STANDARD 

$10 

FALSE if menu is a standard (not custom) menu. 

M NO XOR 

$20 

TRUE if menu title is highlighted using XOR. 

M_NORMAL 

$40 

TRUE if menu title is highlighted. 

M_ENABLED 

$80 

FALSE if menu is disabled. 

mDrawMsg 

0 

Draw menu command 

mChooseMsg 

1 

Hit test item command, 

mSizeMsg 

2 

Compute menu size command 

mDrawTile 

3 

Draw menu's title command 


Posiible inputs to SetMenuFlag: 


EnableMenu • $FF7F 
DisableMenu $0080 
UnhiliteMenu $FFBF 
HiliteMenu $0040 
ColorReplace $FFDF 
XORhilite $0020 
StandardMenu $FFE7 
CustomMenu $0010 


Menu win not be dimmed and will be selectable. 

Menu will be dimmed and not selectable. 

Menu will appear in its highlighted state. 

Menu wiU appear in its normal (unhighlighted) state. 

The menu's title and background will be redrawn to hilite. 
The menu's title area win be XORed to hilite. 

The menu will be considered a standard menu. 

The menu win be considered a custom menu. 


Possible New Value input to SetltemFlag: 

UnderItem $0040 

NoUnderltem $FFBF 

'XORHilite $0020 

NoXORHilite $FFDF 


Underline item. 

Do not underline item. 

Use XOR higldighting on item. 
Use redraw highlighting on item. 
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TaskRee (TaskMasta’ record): 


what . 

0 

Integer 

Same as event record. 

message 

2 

Longlnt 

Same as event record. 

when 

6 

Longlnt 

Same as event record. 

where 

10 

Longlnt 

Same as event record. 

modifiers 

14 

Integer 

Same as event record. 

TaskData 

16 

Longlnt 

Return for ID numbers. 

TaskMask 

20 

Integer 

Unused. 

TASKREC_SIZE 22 

MENUBAR (Menu Bar Record): 


Size of TaskRee. 

CtrlNext 

0 

Handle 

Not used. 

CtrlOwner 

4 

Pointer 

Pointer to menu bar's window. 

CtrlRect 

8 

RECT 

Enclosing rectangle. 

CtrlFlag 

16 

Byte 

Bit flags. 

CtrlHilite 

17 

Byte 

Not used. 

CtrlValue 

18 

Integer 

Not used. 

CtrlProc 

20 

Pointer 

Not used. 

CtrlAction 

24 

Pointer 

Not used. 

CtrlData 

28 

Longlnt 

Reserved for CtrlProc's use. 

CtrlRefCon 

32 

Longlnt 

Reserved for application's use. 

CtrlColor 

36 

Pointer 

Menu bar’s color table. 

MenuList 

40 

Handle[] 

Menu bar's color table. 

MENU (Menu record): 

MenuID 

0 

Integer 

Menu’s ID number. 

. MenuWidth 

2 

Integer 

Width of menu. 

MenuHeight 

4 

Integer 

Height of menu. 

MenuProc 

6 

Pointer 

Menu's definition procedure. 

MenuFlag 

10 

Byte 

Bit flags. 

TitleWidth 

11 

Integer 

Width of menu's tide. 

TitleName 
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